Elevate Oz cloud agents & orchestration to a top-level section + fix top-nav overflow by rachaelrenk · Pull Request #262 · warpdotdev/docs

rachaelrenk · 2026-06-26T21:43:48Z

Summary

Elevates the Oz Cloud Agents & Orchestration subsection from the Agents tab's sidebar into its own top-level section in the horizontal header navigation, positioned between Agents and Reference. Also fixes the header topic-nav so it wraps instead of disappearing on narrow viewports.

Content move

Moved src/content/docs/agent-platform/cloud-agents/* → src/content/docs/platform/* (49 files, via git mv).
overview.mdx → platform/index.mdx (landing at /platform/).
platform.mdx ("Oz Platform overview") → platform/overview.mdx (/platform/overview).
Directory is named platform/ pre-emptively for the upcoming product rename; the nav label is Oz for now.

Navigation

New top-level Oz topic in src/sidebar.ts (link: '/platform/') between Agents and Reference, with all items re-slugged to platform/*. Memory stays under Agents.
Added a cloud icon for the Oz tab in WarpTopicNav.astro (with cloud-download as the mobile-drawer fallback).

Crosslinks, redirects, config

Rewrote ~700 internal references (/agent-platform/cloud-agents/... → /platform/...) across content, plus the docs.warp.dev/... absolutes; also updated AGENTS.md, astro.config.mjs, the SEO script, and .agents/skills/**.
vercel.json: repointed 143 destinations to /platform/..., kept the 36 legacy sources, and appended new source rules (explicit overview / platform / bare variants before a :path* wildcard).
Added an Oz Platform llms customSet for platform/** and trimmed the Agent Platform set.

Top-nav overflow fix

The header topic-nav now wraps to a second row instead of clipping when the window is narrow (removed overflow: hidden, added flex-wrap: wrap).
--sl-nav-height grows to 5rem in the crowded width range so a wrapped row doesn't overlap page content.

Testing

npm run build ✓ (339 pages)
npm run typecheck (astro check) ✓ (0 errors / 0 warnings)
python3 scripts/check_redirects.py ✓ (only wildcard destinations flagged, consistent with the 5 pre-existing wildcards)
0 residual agent-platform/cloud-agents references in content
⚠️ Not yet verified in a browser: the responsive wrap behavior (resize ~50–90rem) and the active-tab underline placement when wrapped — please sanity-check and tweak the 5rem / breakpoint in warp-components.css if needed.

Notes

Caught and fixed a find/replace over-match that had corrupted the cloud-agents-infra.png asset reference; verified platform-credits links were untouched.

Plan: https://staging.warp.dev/drive/notebook/kH9pKwGM438cckB6SCAzyi
Conversation: https://staging.warp.dev/conversation/c5139d33-a19a-40d0-bc5e-56f25c1a051f

Co-Authored-By: Oz oz-agent@warp.dev

Move agent-platform/cloud-agents/* to a new top-level platform/ directory and add an 'Oz' top-level nav tab between Agents and Reference. Repoint all crosslinks and vercel.json redirects to /platform/*, add an Oz Platform llms customSet, and fix the header topic-nav to wrap to a second row instead of clipping on narrow viewports (bumping --sl-nav-height in the crowded range so content isn't overlapped). Co-Authored-By: Oz <oz-agent@warp.dev>

vercel · 2026-06-26T21:43:54Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 27, 2026 12:28am

oz-for-oss · 2026-06-26T21:44:05Z

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR moves the Oz cloud agents docs into a top-level platform/ section, updates sidebar/navigation, redirects, and route references, and adjusts header wrapping behavior. The route move and navigation tree look mechanically consistent, but several updated authoring/audit references now point to platform.md, which does not exist after the landing page moved to platform/index.mdx.

Concerns

Stale platform.md references in drafting guidance and the missing-docs surface map will point contributors or automation at nonexistent files; the audit resolver handles .md/.mdx variants but not directory index pages.

Verdict

Found: 0 critical, 3 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

The meta-file sweep collapsed the old cloud-agents/overview file path to a nonexistent 'platform.md'; point these AGENTS.md, draft_conceptual, and feature_surface_map references at the real landing file 'platform/index.mdx'. Co-Authored-By: Oz <oz-agent@warp.dev>

rachaelrenk · 2026-06-27T00:26:31Z

/oz-review

oz-for-oss · 2026-06-27T00:26:48Z

@rachaelrenk

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR moves the Oz cloud agents and orchestration documentation into a new top-level platform section, updates sidebar and llms.txt grouping, refreshes internal links and redirects, and adjusts the header topic nav to wrap at crowded widths. I reviewed the attached annotated diff, including the docs migration, navigation/config changes, redirect updates, security-relevant content, and the empty spec context.

Concerns

No blocking concerns found.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

hongyi-chen · 2026-06-27T01:20:54Z


 * [Agent API & SDK](https://docs.warp.dev/reference/api-and-sdk/agent) — API reference
-* [Cloud Agents Overview](https://docs.warp.dev/agent-platform/cloud-agents/overview) — How cloud agents work
+* [Cloud Agents Overview](https://docs.warp.dev/platform) — How cloud agents work


i assume we don't need to link to the "overview" pages right?

hongyi-chen · 2026-06-27T01:22:18Z

 * [Skills](/agent-platform/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks.
 * [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have.
-* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - Run background agents with team-wide observability.
+* [Cloud agents overview](/platform/) - Run background agents with team-wide observability.


similarly, just want to double check if we also need to link an overview page? i assume this is the same as above

hongyi-chen · 2026-06-27T01:27:08Z

    },
    {
      "source": "/agent-platform/agent-mode/ambient-agents-session-sharing",
-      "destination": "/agent-platform/cloud-agents/viewing-cloud-agent-runs/",


we shouldn't just change the redirects from the old links, we should also add brand new redirects from these old destination links

e.g. /agent-platform/cloud-agents/viewing-cloud-agent-runs/ should go to /agent-platform/cloud-agents/viewing-cloud-agent-runs/

ah i see these are added at the end, but i think we should also test them quite thoroughly. i see that it supports path matching via /agent-platform/cloud-agents/:path*, but would also like us to manually test a bit too!

hongyi-chen

could we change these sidebar items such that they're not all first level items? i.e. i think quickstart and others can live under cloud agents overview, and we can create a couple of groupings for these

cla-bot Bot added the cla-signed label Jun 26, 2026

vercel Bot deployed to Preview June 26, 2026 21:45 View deployment

oz-for-oss Bot reviewed Jun 26, 2026

View reviewed changes

Comment thread .agents/skills/draft_conceptual/SKILL.md Outdated

Comment thread .agents/skills/missing_docs/references/feature_surface_map.md Outdated

Comment thread AGENTS.md Outdated

rachaelrenk self-assigned this Jun 26, 2026

vercel Bot deployed to Preview June 27, 2026 00:21 View deployment

Merge branch 'main' into rrenk/elevate-platform-section

b925cef

vercel Bot deployed to Preview June 27, 2026 00:28 View deployment

oz-for-oss Bot reviewed Jun 27, 2026

View reviewed changes

hongyi-chen approved these changes Jun 27, 2026

View reviewed changes

hongyi-chen requested changes Jun 27, 2026

View reviewed changes

Uh oh!

Conversation

rachaelrenk commented Jun 26, 2026

Summary

Content move

Navigation

Crosslinks, redirects, config

Top-nav overflow fix

Testing

Notes

Uh oh!

vercel Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rachaelrenk commented Jun 27, 2026

Uh oh!

oz-for-oss Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Jun 26, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 26, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 27, 2026 •

edited

Loading